
/*
 * Copyright 2002-2014 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2014原作者。
 *
 *根据Apache许可证2.0版许可（“许可证”）；
 *除非符合许可证的规定，否则您不得使用此文件。
 *您可以在以下网址获取许可证副本：
 *
 *https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证进行的分发是在“按原样”的基础上进行的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限的特定语言，请参阅许可证
 *许可下的限制。
 */

package org.springframework.mail.javamail;

import java.io.InputStream;

import jakarta.mail.internet.MimeMessage;

import org.springframework.mail.MailException;
import org.springframework.mail.MailSender;

/**
 * Extended {@link org.springframework.mail.MailSender} interface for JavaMail,
 * supporting MIME messages both as direct arguments and through preparation
 * callbacks. Typically used in conjunction with the {@link MimeMessageHelper}
 * class for convenient creation of JavaMail {@link MimeMessage MimeMessages},
 * including attachments etc.
 *
 * <p>Clients should talk to the mail sender through this interface if they need
 * mail functionality beyond {@link org.springframework.mail.SimpleMailMessage}.
 * The production implementation is {@link JavaMailSenderImpl}; for testing,
 * mocks can be created based on this interface. Clients will typically receive
 * the JavaMailSender reference through dependency injection.
 *
 * <p>The recommended way of using this interface is the {@link MimeMessagePreparator}
 * mechanism, possibly using a {@link MimeMessageHelper} for populating the message.
 * See {@link MimeMessageHelper MimeMessageHelper's javadoc} for an example.
 *
 * <p>The entire JavaMail {@link jakarta.mail.Session} management is abstracted
 * by the JavaMailSender. Client code should not deal with a Session in any way,
 * rather leave the entire JavaMail configuration and resource handling to the
 * JavaMailSender implementation. This also increases testability.
 *
 * <p>A JavaMailSender client is not as easy to test as a plain
 * {@link org.springframework.mail.MailSender} client, but still straightforward
 * compared to traditional JavaMail code: Just let {@link #createMimeMessage()}
 * return a plain {@link MimeMessage} created with a
 * {@code Session.getInstance(new Properties())} call, and check the passed-in
 * messages in your mock implementations of the various {@code send} methods.
 *
 * @author Juergen Hoeller
 * @since 07.10.2003
 * @see jakarta.mail.internet.MimeMessage
 * @see jakarta.mail.Session
 * @see JavaMailSenderImpl
 * @see MimeMessagePreparator
 * @see MimeMessageHelper
 */
/**
 *JavaMail的扩展{@linkorg.springframework.mail.MailSender}接口，
 *支持MIME消息作为直接参数和通过准备
 *回调。通常与｛@link MimeMessageHelper｝一起使用
 *类，用于方便地创建JavaMail｛@link MimeMessage MimeMessages｝，
 *包括附件等。
 *
 *<p>如果需要，客户端应通过此接口与邮件发件人交谈
 *｛@linkorg.springframework.mail.SimpleMailMessage｝之外的邮件功能。
 *生产实现是｛@link JavaMailSenderImpl｝；为了测试，
 *可以基于该接口创建mock。客户通常会收到
 *JavaMailSender引用。
 *
 *<p>推荐使用此接口的方法是｛@link MimeMessagePreparator｝
 *机制，可能使用{@link-MimeMessageHelper}来填充消息。
 *有关示例，请参阅｛@link MimeMessageHelper MimeMessageHelp的javadoc｝。
 *
 *＜p＞整个JavaMail｛@link jakarta.mail.Session｝管理是抽象的
 *通过JavaMailSender。客户端代码不应以任何方式处理会话，
 *而是将整个JavaMail配置和资源处理留给
 *JavaMailSender实现。这也增加了可测试性。
 *
 *<p>JavaMailSender客户端不像普通客户端那样容易测试
 *{@linkorg.springframework.mail.MailSender}客户端，但仍然很简单
 *与传统的JavaMail代码相比：只需让{@link#createMimeMessage（）}
 *返回使用
 *｛@code Session.getInstance（new Properties（））｝调用，并检查传入的
 *各种{@code-send}方法的mock实现中的消息。
 *
 *@作者Juergen Hoeller
 *@自2003年10月7日起
 *@见jakarta.mail.internet.MimeMessage
 *@见jakarta.mail.Session
 *@参见JavaMailSenderImpl
 *@see MimeMessagePreparator
 *@see MimeMessageHelper
 */
public interface JavaMailSender extends MailSender {

	/**
	 * Create a new JavaMail MimeMessage for the underlying JavaMail Session
	 * of this sender. Needs to be called to create MimeMessage instances
	 * that can be prepared by the client and passed to send(MimeMessage).
	 * @return the new MimeMessage instance
	 * @see #send(MimeMessage)
	 * @see #send(MimeMessage[])
	 */
	/**
	 *为基础JavaMail会话创建新的JavaMail MimeMessage
	 *此发件人的。需要调用以创建MimeMessage实例
	 *可以由客户端准备并传递给发送（MimeMessage）。
	 *@返回新的MimeMessage实例
	 *@see#发送（MimeMessage）
	 *@see#发送（MimeMessage[]）
	 */
	MimeMessage createMimeMessage();

	/**
	 * Create a new JavaMail MimeMessage for the underlying JavaMail Session
	 * of this sender, using the given input stream as the message source.
	 * @param contentStream the raw MIME input stream for the message
	 * @return the new MimeMessage instance
	 * @throws org.springframework.mail.MailParseException
	 * in case of message creation failure
	*/
	/**
	 *为基础JavaMail会话创建新的JavaMail MimeMessage
	 *使用给定的输入流作为消息源。
	 *@param contentStream消息的原始MIME输入流
	 *@返回新的MimeMessage实例
	 *@throws org.springframework.mail.MailParseException
	 *在消息创建失败的情况下
	*/
	MimeMessage createMimeMessage(InputStream contentStream) throws MailException;

	/**
	 * Send the given JavaMail MIME message.
	 * The message needs to have been created with {@link #createMimeMessage()}.
	 * @param mimeMessage message to send
	 * @throws org.springframework.mail.MailAuthenticationException
	 * in case of authentication failure
	 * @throws org.springframework.mail.MailSendException
	 * in case of failure when sending the message
	 * @see #createMimeMessage
	 */
	/**
	 *发送给定的JavaMail MIME消息。
	 *该消息需要使用{@link#createMimeMessage（）}创建。
	 *@param mimeMessage要发送的消息
	 *@throws org.springframework.mail.MailAuthenticationException
	 *在身份验证失败的情况下
	 *@throws org.springframework.mail.MailSendException
	 *在发送消息时发生故障
	 *@参见#createMimeMessage
	 */
	void send(MimeMessage mimeMessage) throws MailException;

	/**
	 * Send the given array of JavaMail MIME messages in batch.
	 * The messages need to have been created with {@link #createMimeMessage()}.
	 * @param mimeMessages messages to send
	 * @throws org.springframework.mail.MailAuthenticationException
	 * in case of authentication failure
	 * @throws org.springframework.mail.MailSendException
	 * in case of failure when sending a message
	 * @see #createMimeMessage
	 */
	/**
	 *批量发送给定的JavaMail MIME消息数组。
	 *消息需要使用{@link#createMimeMessage（）}创建。
	 *@param mimeMessages要发送的消息
	 *@throws org.springframework.mail.MailAuthenticationException
	 *在身份验证失败的情况下
	 *@throws org.springframework.mail.MailSendException
	 *在发送消息时发生故障
	 *@参见#createMimeMessage
	 */
	void send(MimeMessage... mimeMessages) throws MailException;

	/**
	 * Send the JavaMail MIME message prepared by the given MimeMessagePreparator.
	 * <p>Alternative way to prepare MimeMessage instances, instead of
	 * {@link #createMimeMessage()} and {@link #send(MimeMessage)} calls.
	 * Takes care of proper exception conversion.
	 * @param mimeMessagePreparator the preparator to use
	 * @throws org.springframework.mail.MailPreparationException
	 * in case of failure when preparing the message
	 * @throws org.springframework.mail.MailParseException
	 * in case of failure when parsing the message
	 * @throws org.springframework.mail.MailAuthenticationException
	 * in case of authentication failure
	 * @throws org.springframework.mail.MailSendException
	 * in case of failure when sending the message
	 */
	/**
	 *发送由给定MimeMessagePreparator准备的JavaMail MIME消息。
	 *<p>准备MimeMessage实例的替代方法，而不是
	 *｛@link#createMimeMessage（）｝和｛@link#send（MimeMessage）｝调用。
	 *负责正确的异常转换。
	 *@param mimeMessagePreparator要使用的preparator
	 *@throws org.springframework.mail.MailPreparationException
	 *在准备消息时发生故障
	 *@throws org.springframework.mail.MailParseException
	 *在解析消息时出错
	 *@throws org.springframework.mail.MailAuthenticationException
	 *在身份验证失败的情况下
	 *@throws org.springframework.mail.MailSendException
	 *在发送消息时发生故障
	 */
	void send(MimeMessagePreparator mimeMessagePreparator) throws MailException;

	/**
	 * Send the JavaMail MIME messages prepared by the given MimeMessagePreparators.
	 * <p>Alternative way to prepare MimeMessage instances, instead of
	 * {@link #createMimeMessage()} and {@link #send(MimeMessage[])} calls.
	 * Takes care of proper exception conversion.
	 * @param mimeMessagePreparators the preparator to use
	 * @throws org.springframework.mail.MailPreparationException
	 * in case of failure when preparing a message
	 * @throws org.springframework.mail.MailParseException
	 * in case of failure when parsing a message
	 * @throws org.springframework.mail.MailAuthenticationException
	 * in case of authentication failure
	 * @throws org.springframework.mail.MailSendException
	 * in case of failure when sending a message
	 */
	/**
	 *发送由给定MimeMessagePreparators准备的JavaMail MIME消息。
	 *<p>准备MimeMessage实例的替代方法，而不是
	 *｛@link#createMimeMessage（）｝和｛@link#send（MimeMessage[]）｝调用。
	 *负责正确的异常转换。
	 *@param mimeMessagePreparators指定要使用的preparator
	 *@throws org.springframework.mail.MailPreparationException
	 *在准备消息时发生故障
	 *@throws org.springframework.mail.MailParseException
	 *在解析消息时出错
	 *@throws org.springframework.mail.MailAuthenticationException
	 *在身份验证失败的情况下
	 *@throws org.springframework.mail.MailSendException
	 *在发送消息时发生故障
	 */
	void send(MimeMessagePreparator... mimeMessagePreparators) throws MailException;

}
